Datenübertragung

Webservices werden verwendet, um Transaktionsdaten zwischen dem das Hostsystem und Vocollect VoiceCheck zu senden. VoiceCheck unterstützt sowohl SOAP- als auch REST-Webservices. Diese Services stellen die Import- und die Exportfunktion für das VoiceCheck-System bereit.

Die Services und die Meldungsformate werden unten ausführlich beschrieben, und im Produktpaket ist je eine Referenz-XML-Datei für SOAP Web Service Description Language (WSDL) und REST Web Application Description Language (WADL) zu finden. Bislang konnten Beschreibungen der Services durch Eingabe von http://<Host>:<Port>/VoiceCheck/services/api/swagger.json in Ihren Webbrowser aufgerufen werden. Dieser Link ersetzt nun den bisherigen Link: http://<Host>:<Port>/VoiceCheck/services.

Webservices-Meldungsfluss

Konfiguration und Sicherheit

Die gesamte Kommunikation erfolgt, abhängig von der Konfiguration von VoiceCheck, über HTTP oder HTTPS.

Beim Datenimport verlangen alle von VoiceCheck bereitgestellten SOAP-Webservices die Authentifizierung mit WS-Security UsernameToken. Sämtliche REST-Webservices für den Import setzen die Authentifizierung mit der HTTP-Basisauthentifizierung voraus.

VoiceCheck verfügt über eine in der Benutzeroberfläche konfigurierbare Zugriffsrolle, nach der sich richtet, welche Webservices ein Benutzer ausführen darf. Die Webservice-Clients des Hostsystems müssen für die Authentifizierung mit VoiceCheck-Webservices als Benutzer mit dieser Rolle konfiguriert sein.

Beim Datenexport unterstützt VoiceCheck den Einsatz der HTTP-Basisauthentifizierung für den Zugriff auf einen SOAP- oder REST-Webservice auf dem Hostsystem. Die Authentifizierung ist optional. Wenn sie jedoch genutzt wird, wird sie in VoiceCheck konfiguriert, und das Kennwort wird verschlüsselt und in der VoiceCheck-Datenbank gespeichert.

VoiceCheck bietet auch eine Methode zum Konfigurieren der Webservice-Endpunkt-URL für die von das Hostsystem bereitgestellten Services. Diese Endpunkt-URL ist eine obligatorische Einstellung in der Benutzeroberfläche.

Für alle Services, die das Hostsystem für VoiceCheck bereitstellt, gelten derselbe Benutzername und dasselbe Kennwort. Derzeit gibt es nur einen Service, der für VoiceCheck bereitgestellt wird. Dieser dient zum Senden von Zuweisungsergebnissen an das Hostsystem.

Die Konfigurationsinformationen (Webservice-Endpunkt, Webservice-Client-Typ, Benutzername und Kennwort) werden auf Systemebene in VoiceCheck eingerichtet. Diese Einstellungen sind auf der Seite Administrator > Systemkonfiguration zu finden. Die Konfiguration geht davon aus, dass eine Instanz von VoiceCheck eine Verbindung zu genau einem Hostsystem-Endpunkt herstellt.

XML-Schemas und Namespaces

VoiceCheck deklariert einen Namespace für alle in SOAP- und REST-Services verwendeten XML-Elemente. Ausgenommen hiervon ist lediglich das Element faultInfo (siehe Anmerkung unten). Der Namespace lautet:

http://service.web.voicecheck.vocollect.com/

Bei SOAP-Services, die VoiceCheck für den Datenimport bereitstellt, sind der Namespace und das Schema in der WSDL-Datei zu finden.

Bei REST-Services, die VoiceCheck für den Datenimport bereitstellt, sind der Namespace und das Schema in der WADL-Datei zu finden. Beim Webservice "Zuweisung erstellen" ist es zwar nicht unbedingt erforderlich, dass REST-Clients den XML-Code mit dem Namespace qualifizieren, es wird aber dringend empfohlen.

Beim REST-Service, den VoiceCheck zum Senden von Zuweisungsergebnissen an ein Hostsystem nutzt, werden der Namespace und das Schema, das der Server im XML-Code erwartet, in der im Produktpaket bereitgestellten WADL-Beispieldatei definiert.

Das Element faultInfo wird nicht als Teil eines Namespace definiert. Bei REST-Services qualifiziert VoiceCheck das Element nicht mit einem Namespace, wenn es eine Fehlermeldung an ein Hostsystem sendet. Dementsprechend darf das Hostsystem in einer Antwort an VoiceCheck ein faultInfo-Element nicht mit einem Namespace qualifizieren.

Fehlerbehebung bei Zuweisungsdaten

REST-Fehlerbehebung

Bei einem Fehler können, je nach Art und Ort des Fehlers während der Verarbeitung, verschiedene HTTP-Statuscodes zurückgegeben werden. VoiceCheck nutzt für die Verarbeitung von Webservice-Anforderungen das Apache^® CXF-Framework, und das Framework kann während der Verarbeitung Fehler wie „406 – Not Acceptable“ (Nicht annehmbar) oder „415 – Unsupported Media Type“ (Nicht unterstützter Medientyp) zurückgeben, bevor die VoiceCheck-Geschäftslogik erreicht ist.

Für Fehler, die aus der VoiceCheck-Geschäftslogik herrühren, gibt es nur zwei mögliche Statuscodes:

• 400 – Bad Request (Ungültige Anforderung): Der Client hat gegen eine Geschäftsregel oder Beschränkung verstoßen (in der Regel ungültige Daten). Das erneute Senden der unveränderten Meldung führt zum selben Fehler.
• 500 – Internal Server Error (Interner Serverfehler): Beim Verarbeiten der Anforderung ist ein interner Serverfehler aufgetreten. Das erneute Senden der Meldung KANN erfolgreich sein.

Fehler, die aus der VoiceCheck-Geschäftslogik herrühren, enthalten außerdem ein faultInfo-XML-Element, dem zusätzliche Informationen zum aufgetretenen Fehler entnommen werden können. Die Eigenschaften des faultInfo-Elements sind unten beschrieben.

SOAP-Fehlerbehebung

Für alle Fehler werden SOAP 1.1-Fehler zurückgegeben. Sie enthalten alle einen Fehlercode und eine Fehlerzeichenfolge gemäß SOAP 1.1. Bei den meisten Fehlern werden zwei der SOAP 1.1-Kernfehlercodes angegeben: "Client" und Server". VoiceCheck verwendet diese Codes generell in der in der SOAP 1.1-Spezifikation beschriebenen Weise.

Bei einigen Fehlern, die während der Authentifizierung auftreten können, kommen in WS-Security (Web Services Security) spezifizierte Fehlercodes zum Einsatz. Die Java-Webservices-APIs und -Implementierungen können andere Fehlercodes zurückgeben.

Auch wenn es nicht möglich ist, alle denkbaren Fehlercodes aufzulisten, gibt es aber allgemeine Regeln, die eine einheitliche Fehlerbehebung durch Webservices-Clients ermöglichen können:

• Mit Ausnahme von Server-Fehlercodes bedeutet die Ausgabe von Fehlercodes in der Regel, dass es nicht sinnvoll ist, die Meldung automatisch noch einmal zu senden. Die Codes werden gesendet, wenn der Client etwas falsch gemacht hat, bevor die Übertragung die Anwendungslogik auf dem Server erreicht. Beispiele hierfür sind Authentifizierungsfehler oder falsch aufgesetzte Meldungen.
• Lautet der Fehlercode „Server“ und stammt der Fehler aus der Anwendungsserverlogik, enthält er das SOAP 1.1-Fehlerdetailelement (faultInfo). Das genaue Format wird in der WSDL-Datei spezifiziert, aber es enthält die im folgenden Abschnitt genannten Informationen.

Element „faultInfo“

Wenn ein Fehler aus der VoiceCheck-Anwendungsserverlogik stammt, enthalten der REST- und der SOAP-Webservice dieselben Fehlerinformationen.

Die Hostserver-REST-Implementierung für das Senden von Zuweisungsergebnissen muss dieses faultInfo-Element verwenden, damit die Fehlermeldung in der VoiceCheck-Benutzeroberfläche angezeigt werden kann. Anderenfalls sieht der Benutzer eine allgemeine Meldung.

Eigenschaft	Typ	Definition
errorCode	Long	Numerischer Code, der für den Fehler steht Gültige Werte: 3000 = Internal Server Error (Interner Serverfehler) (eine Wiederholung kann zum Erfolg führen, muss aber nicht) 3001 = Bad Request (Ungültige Anforderung) (von einer automatischen Wiederholung der Anforderung wird abgeraten)
message	Zeichenfolge	Für Menschen verständliche Meldung zur Erläuterung des Fehlers